1 /*
2 * Copyright (C) 2007 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package com.google.common.collect;
18
19 import com.google.common.annotations.GwtCompatible;
20
21 import java.util.Collection;
22 import java.util.Comparator;
23 import java.util.Map;
24 import java.util.Set;
25 import java.util.SortedSet;
26
27 import javax.annotation.Nullable;
28
29 /**
30 * A {@code SetMultimap} whose set of values for a given key are kept sorted;
31 * that is, they comprise a {@link SortedSet}. It cannot hold duplicate
32 * key-value pairs; adding a key-value pair that's already in the multimap has
33 * no effect. This interface does not specify the ordering of the multimap's
34 * keys. See the {@link Multimap} documentation for information common to all
35 * multimaps.
36 *
37 * <p>The {@link #get}, {@link #removeAll}, and {@link #replaceValues} methods
38 * each return a {@link SortedSet} of values, while {@link Multimap#entries()}
39 * returns a {@link Set} of map entries. Though the method signature doesn't say
40 * so explicitly, the map returned by {@link #asMap} has {@code SortedSet}
41 * values.
42 *
43 * <p>See the Guava User Guide article on <a href=
44 * "http://code.google.com/p/guava-libraries/wiki/NewCollectionTypesExplained#Multimap">
45 * {@code Multimap}</a>.
46 *
47 * @author Jared Levy
48 * @since 2.0 (imported from Google Collections Library)
49 */
50 @GwtCompatible
51 public interface SortedSetMultimap<K, V> extends SetMultimap<K, V> {
52 // Following Javadoc copied from Multimap.
53
54 /**
55 * Returns a collection view of all values associated with a key. If no
56 * mappings in the multimap have the provided key, an empty collection is
57 * returned.
58 *
59 * <p>Changes to the returned collection will update the underlying multimap,
60 * and vice versa.
61 *
62 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given
63 * key, this method returns a {@link SortedSet}, instead of the
64 * {@link java.util.Collection} specified in the {@link Multimap} interface.
65 */
66 @Override
67 SortedSet<V> get(@Nullable K key);
68
69 /**
70 * Removes all values associated with a given key.
71 *
72 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given
73 * key, this method returns a {@link SortedSet}, instead of the
74 * {@link java.util.Collection} specified in the {@link Multimap} interface.
75 */
76 @Override
77 SortedSet<V> removeAll(@Nullable Object key);
78
79 /**
80 * Stores a collection of values with the same key, replacing any existing
81 * values for that key.
82 *
83 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given
84 * key, this method returns a {@link SortedSet}, instead of the
85 * {@link java.util.Collection} specified in the {@link Multimap} interface.
86 *
87 * <p>Any duplicates in {@code values} will be stored in the multimap once.
88 */
89 @Override
90 SortedSet<V> replaceValues(K key, Iterable<? extends V> values);
91
92 /**
93 * Returns a map view that associates each key with the corresponding values
94 * in the multimap. Changes to the returned map, such as element removal, will
95 * update the underlying multimap. The map does not support {@code setValue()}
96 * on its entries, {@code put}, or {@code putAll}.
97 *
98 * <p>When passed a key that is present in the map, {@code
99 * asMap().get(Object)} has the same behavior as {@link #get}, returning a
100 * live collection. When passed a key that is not present, however, {@code
101 * asMap().get(Object)} returns {@code null} instead of an empty collection.
102 *
103 * <p><b>Note:</b> The returned map's values are guaranteed to be of type
104 * {@link SortedSet}. To obtain this map with the more specific generic type
105 * {@code Map<K, SortedSet<V>>}, call
106 * {@link Multimaps#asMap(SortedSetMultimap)} instead.
107 */
108 @Override Map<K, Collection<V>> asMap();
109
110 /**
111 * Returns the comparator that orders the multimap values, with {@code null}
112 * indicating that natural ordering is used.
113 */
114 Comparator<? super V> valueComparator();
115 }